"""
缓存管理抽象接口
==============

定义缓存管理器的抽象基类，所有具体的缓存实现都应该继承此接口。
"""

from abc import ABC, abstractmethod
from typing import Any, Optional, Union, Dict, List
import asyncio


class AbstractCacheManager(ABC):
    """抽象缓存管理器"""
    
    @abstractmethod
    async def get(self, key: str) -> Optional[Any]:
        """
        获取缓存值
        
        Args:
            key: 缓存键
            
        Returns:
            缓存值，不存在则返回None
        """
        pass
    
    @abstractmethod
    async def set(
        self, 
        key: str, 
        value: Any, 
        expire: Optional[int] = None
    ) -> bool:
        """
        设置缓存值
        
        Args:
            key: 缓存键
            value: 缓存值
            expire: 过期时间（秒），None表示不过期
            
        Returns:
            是否设置成功
        """
        pass
    
    @abstractmethod
    async def delete(self, key: str) -> bool:
        """
        删除缓存
        
        Args:
            key: 缓存键
            
        Returns:
            是否删除成功
        """
        pass
    
    @abstractmethod
    async def exists(self, key: str) -> bool:
        """
        检查缓存是否存在
        
        Args:
            key: 缓存键
            
        Returns:
            是否存在
        """
        pass
    
    @abstractmethod
    async def expire(self, key: str, seconds: int) -> bool:
        """
        设置缓存过期时间
        
        Args:
            key: 缓存键
            seconds: 过期时间（秒）
            
        Returns:
            是否设置成功
        """
        pass
    
    @abstractmethod
    async def ttl(self, key: str) -> int:
        """
        获取缓存剩余生存时间
        
        Args:
            key: 缓存键
            
        Returns:
            剩余时间（秒），-1表示不过期，-2表示不存在
        """
        pass
    
    @abstractmethod
    async def clear(self, pattern: Optional[str] = None) -> int:
        """
        清除缓存
        
        Args:
            pattern: 键模式，None表示清除所有
            
        Returns:
            清除的键数量
        """
        pass
    
    @abstractmethod
    async def mget(self, keys: List[str]) -> Dict[str, Any]:
        """
        批量获取缓存值
        
        Args:
            keys: 缓存键列表
            
        Returns:
            键值对字典
        """
        pass
    
    @abstractmethod
    async def mset(self, mapping: Dict[str, Any], expire: Optional[int] = None) -> bool:
        """
        批量设置缓存值
        
        Args:
            mapping: 键值对字典
            expire: 过期时间（秒）
            
        Returns:
            是否设置成功
        """
        pass
    
    @abstractmethod
    async def incr(self, key: str, amount: int = 1) -> int:
        """
        递增计数器
        
        Args:
            key: 缓存键
            amount: 递增量
            
        Returns:
            递增后的值
        """
        pass
    
    @abstractmethod
    async def decr(self, key: str, amount: int = 1) -> int:
        """
        递减计数器
        
        Args:
            key: 缓存键
            amount: 递减量
            
        Returns:
            递减后的值
        """
        pass
    
    @abstractmethod
    async def health_check(self) -> Dict[str, Any]:
        """
        健康检查
        
        Returns:
            健康状态信息
        """
        pass
    
    @abstractmethod
    async def close(self):
        """关闭连接"""
        pass


class AbstractCacheConfig(ABC):
    """抽象缓存配置"""
    
    @property
    @abstractmethod
    def host(self) -> str:
        """缓存服务主机"""
        pass
    
    @property
    @abstractmethod
    def port(self) -> int:
        """缓存服务端口"""
        pass
    
    @property
    @abstractmethod
    def password(self) -> Optional[str]:
        """缓存服务密码"""
        pass
    
    @property
    @abstractmethod
    def database(self) -> int:
        """缓存数据库编号"""
        pass
    
    @property
    @abstractmethod
    def max_connections(self) -> int:
        """最大连接数"""
        pass
    
    @property
    @abstractmethod
    def connection_timeout(self) -> int:
        """连接超时时间"""
        pass
